/**
 * Copyright 2008-2009. Chongqing Communications Industry Services Co.,Ltd Information Technology Branch. All rights
 * reserved. <a>http://www.cqcis.com</a>
 */
package com.cqcis.uip.base.framework.service;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

import org.apache.commons.net.ftp.FTPClient;

import com.cqcis.uip.base.framework.common.FtpFile;

/**
 * FTP链接抽象,代表一个FTP链接，可以通过改session中的方法对远程服务器进行操作.
 * 
 * @author huangmy
 * @date   2008-8-16
 */
public interface FtpSession {
	/**
	 * 将本地local输入流中的数据以remoteFileName文件名保存在
	 * 远程FTP服务器上
	 * 
	 * @param remoteFileName  远程服务器文件名
	 * @param local           本地输入流, 该方法将不会关闭输入流,输入流的关闭原则是谁创建，谁负责关闭.
	 * @return 保存成功，返回true；失败，返回false
	 * @throws Exception 
	 */
	public boolean storeFile(String remoteFileName, InputStream local) throws Exception;
	
	/**
	 * 获取指定远程文件名的文件流，可以利用该文件流将数据保存到远程服务器上。
	 * 调用方必须负责将文件流关闭.
	 * 
	 * @param remoteFileName 远程服务器文件名
	 * @return   返回文件流
	 * @throws Exception
	 */
	public OutputStream getStoreStream(String remoteFileName) throws Exception;
	
	/**
	 * 将本地local输入流中的数据以追加到远程服务器上，名为remoteFileName的文件上。
	 * 
	 * @param remoteFileName 远程服务器文件名
	 * @param local          本地输入流, 该方法将不会关闭输入流,输入流的关闭原则是谁创建，谁负责关闭.
	 * @return 保存成功，返回true；失败，返回false
	 * @throws Exception
	 */
	public boolean appendFile(String remoteFileName, InputStream local) throws Exception;
	
	/**
	 * 获取指定远程文件名的文件流，可以利用该文件流将数据追加保存到远程服务器上。
	 * 调用方必须负责将文件流关闭.
	 * 
	 * @param remoteFileName  远程服务器文件名
	 * @return   返回文件流
	 * @throws Exception
	 */
	public OutputStream getAppendStream(String remoteFileName) throws Exception;
	
	/**
	 * 重命名文件
	 * 
	 * @param from
	 * @param to
	 * @return  成功，返回true；失败，返回false
	 * @throws Exception
	 */
	public boolean rename(String from, String to) throws Exception;
	
	/**
	 * 删除指定的文件
	 * 
	 * @param pathname
	 * @return  成功，返回true；失败，返回false
	 * @throws Exception
	 */
	public boolean delete(String pathname) throws Exception;
	
	/**
	 * 删除指定的文件夹,只有当文件夹为空时才能删除.
	 * 
	 * @param pathname
	 * @return  成功，返回true；失败，返回false
	 * @throws Exception
	 */
	public boolean removeDir(String pathname) throws Exception;
	
	/**
	 * 创建文件夹
	 * 
	 * @param pathname
	 * @return  成功，返回true；失败，返回false
	 * @throws Exception
	 */
	public boolean mkdir(String pathname) throws Exception;
	
	/**
	 * 返回工作目录
	 * 
	 * @return  工作目录路径
	 * @throws Exception
	 */
	public String getWorkDir() throws Exception;
	
	/**
	 * 列出指定目录下的文件名
	 * 
	 * @param pathname
	 * @return
	 * @throws Exception
	 */
	public String[] listNames(String pathname) throws Exception;
	
	/**
	 * 列出当前工作目录下的文件名
	 * 
	 * @return
	 * @throws ExceptionO
	 */
	public String[] listNames() throws Exception;
	
	/**
	 * 列出指定目录下的文件
	 * 
	 * @param pathname
	 * @return
	 * @throws Exception
	 */
	public FtpFile[] listFiles(String pathname) throws Exception;
	
	/**
	 * 列出工作目录下的文件
	 * 
	 * @return
	 * @throws Exception
	 */
	public FtpFile[] listFiles() throws Exception;
	
	/**
	 * 切换到新的工作目录
	 * 
	 * @param newWorkingDir
	 * @return
	 * @throws Exception
	 */
	public boolean cwd(String newWorkingDir) throws Exception;
	
	/**
	 * 获取输入流
	 * 
	 * @param remoteName
	 * @return
	 * @throws IOException
	 */
	public InputStream retrieveFileStream(String remoteName) throws IOException;
	
	/**
	 * 获取数据
	 * 
	 * @param remoteName
	 * @param local
	 * @return True if successfully completed, false if not.
	 * @throws IOException
	 */
	public boolean retrieveFileStream(String remoteName, OutputStream local) throws IOException;
	
	/**
	 * 关闭
	 * 
	 */
	public void close() throws Exception;
	
	/**
	 * stream日志文件保存工具
	 * 
	 * @return
	 */
	public StreamLogOutputService getStreamLogOutputService();
	
	/**
	 * 对于返回流的操作或者异步读取操作，必须执行该方法
	 * 
	 * @return
	 * @throws IOException
	 */
	public boolean completePendingCommand() throws IOException;
	
	/**
	 * 创建 FTP客户端, 使用者需要负责对该client的关闭操作, logout, disconnect
	 * 
	 * @return
	 */
	public FTPClient createFTPClient();
}